McAsm & McLink

Documentation

Version 1.0, dated 7/25/85


Copyright  1985 by Dave McWherter



INTRODUCTION


	McAsm and McLink are an assembler and a linker 
respectively for the Apple Macintosh computer. McAsm is used 
to assemble source files containing Motorola 68000 assembly 
language code and pseudo-ops. McAsm can also assemble 
standard and user-defined resources. McLink  is used to combine 
files produced by McAsm into an executable application program 
file. McAsm and McLink are useable on a 128K Mac as long as the 
programs being assembled and linked aren't too large.


	This manual assumes you are already familiar with 
most of the Macintosh architecture and that you already know 
how to program in 68000 assembly language.


	The file LIST.ASM (or LISTER.LST in CompuServe's 
MacUser's DL3) contains an example application written in 
McAsm that shows how to use many of the features of McAsm 
and McLink.


DISTRIBUTION POLICY


	McAsm and McLink are being distributed under the 
shareware system which is a way of distributing high quality 
software at a low cost. Shareware allows me to distribute 
McAsm and McLink cheaply. It allows you to try them out at no 
charge at your leisure. If you like what you get then you pay me, 
otherwise you just throw it away and you've only spent the cost 
of the download. It might appear that I have a lot of confidence 
that you'll like it enough to send the money. Actually, I'm scared 
to death - please help me to support these programs by 
registering if you use them.


	There are no licensing agreements for McAsm and 
McLink, but since they are copyrighted programs, I will enforce 
the conditions and stipulations set forth on the following page. 
I think they're more than reasonable and that you can live with 
them without any trouble. 


Distribution Conditions & Stipulations


1.) McAsm and McLink are copyrighted programs and the 
copyrights are owned by me,  David M. McWherter, Jr. This 
manual is also copyrighted by me. McAsm and McLink are 
also trademarks of mine. The McAsm and McLink names and 
copyright notices may not be removed from the programs 
or this manual.


2.) You are free to use McAsm and McLInk for your own 
individual use without any restrictions except for those 
mentioned below.


3.) You are free to make as many copies of McAsm and McLink as 
you like, either for your own backup purposes or to give to 
your friends, as long as any such distribution by you is in 
the spirit of shareware. That spirit is that good quality 
software should be made avaliable to users at as low a 
cost as possible and that the author of the program should 
benefit from its distribution. If you do give any copies to 
your friends, then you should include the documentation 
files with the program file.


4.) McAsm and McLink may not be distributed by themselves or 
in combination with any other software or hardware as 
part of a sale, promotion, or marketing effort of any sort 
without my express written consent. The only person 
entitled to make a profit from McAsm and McLink is me.


5.) If, after trying McAsm and McLink, you find that you like 
them and continue to use them for productive work, then I 
ask that you pay for them. The suggested price is $40.00, 
but feel free to pay whatever you think they're worth 
(higher or lower.) If you don't like them and don't use them, 
then please erase all of your copies of them. If you do 
make a payment, then you become a registered user, and 
you'll receive as much support as I can muster. Registered 
users may contact me by phone or CompuServe with any 
problems or questions and I'll do my best to answer them. I 
will not support non-registered users. Registered users 
will also be notified of the availablilty of any updates to 
McAsm and McLink (and other utilities under development.) 
Payment and contact details are at the end of this manual.


6.) McAsm and McLink are only warranted to the extent that if 
they don't do what this manual says they will, then drop 
me a note and I'll either fix the problem or give you your 
money back (if you've sent any.)


	The above six points are the sole extent of the 
agreement between you and I. I do not want your firstborn nor 
your house, and in return I only ask that you'll help me to keep 
mine by supporting this effort. Now that the quasi-legal stuff 
is out of the way, let's get on to the goodies...



MCASM


	McAsm is a 68000 assembler specifically designed 
to run on and produce relocatable files for the Macintosh. Many 
of its features relate directly to features and capabilities of 
the Macintosh itself. McAsm will assemble source files 
containing any combination of 68000 opcodes, McAsm pseudo-
ops, or resource definitions.


	McAsm generates .REL files as output files. .REL 
files are not directly executable and must be linked with the 
McAsm linker to generate an application program file.


	When McAsm is run, it opens an output window on 
the screen. This is the window in which all messages, listings, 
etc. will displayed. The output window's contents will scroll up 
out of the window as data is displayed in the window. Data 
which is scrolled off is lost.


FILE MENU


	The File Menu gives you two options - Assemble or 
Quit. If you select Assemble, then the standard Open File dialog 
box will appear. Select the file you want to assemble and "Open" 
it in any of the normal ways. McAsm will then start assembling 
the file.



OPTION MENU


	The Option Menu gives you the following options:


	* Object file - causes an object file (having the 
same name as

			the source file with a .REL suffix) to be

			stored on the same disk as the source 
file.

	* Listing to printer - causes a listing to be sent to 
the printer

			during assembly.

	* Listing to screen - causes a listing to be sent to 
the screen

			during assembly.

	* Listing to file - causes a listing to be stored in a 
file (having

			the same name as the source file with a 
.LST

			suffix) on the same drive as the source 
file.

	* Errors only listing - causes only lines containing 
errors to be

			listed.

	* Symbol table - causes a symbol table to be output 
at the end

			of the listing.

	* Cross reference - causes a cross reference list to 
be output

			at the end of the listing.


	Any combination of these options is allowed. (Note 
that if you turn off the screen and printer output options then 
you'll have an extremely "quiet" assembly - nothing will be 
output.)


	You can get a listing of just the symbol table or the 
cross reference table by selecting the Errors only listing option 
along with the Symbol table or Cross reference option.


TRANSFER MENU


	The transfer menu lets you transfer control to one 
of the two programs EDIT or LINK without first exiting to the 
Finder. The EDIT or LINK programs must be on the disk from 
which you started McAsm or their transfer menu items will be 
disabled.


SUSPENDING AND ABORTING


	The assembly can be suspended by typing the 
spacebar. You can also restart it the same way. You can abort 
the assembly by typing the backslash key.



SOURCE LINE FORMAT


	McAsm expects source code lines in the following 
format:


	[label]  opcode  [operand]  [;] [comment]


	Tabs are used to separate fields. You can have as 
many tabs as you like before the opcode field and after the 
operand field, but only one tab can appear between the opcode 
and its operand.


	A label is optional in most cases. Labels may contain 
up to 100 characters each. All characters in a label are 
significant. Case distinctions in labels are not significant, 
unless you use the CASE pseudo-op. Labels may contain 
alphanumeric characters and any of the following characters:  
_, %, !, @, #, $, and ?.


	The opcode field may contain any of the standard 
Motorola instruction opcodes, a McAsm pseudo-op, a macro 
name, or the name of a trap word which has been defined with 
the TRAPW pseudo-op.


	The operand field may contain any allowable 
addressing mode operand for the instruction. Addressing mode 
syntaxes are described later.


	The semicolon comment designator character is 
optional in the majority of cases. Specifically, if an opcode 
appears in the line then you can omit the semicolon. If a line 
just contains a label and a comment, then you have to use the 
semicolon.



ADDRESSING MODES


	McAsm supports the following adressing mode 
syntaxes. All of the standard Motorola modes are allowed:



	Address mode	Syntax

	data reg direct			Dn


	address reg direct			An


	register indirect			(An)


	reg indirect, postincrement	(An)+


	predecrement, reg indirect	-(An)


	reg indirect with offset		absexp16(An)


	reg indirect w/offset, indexed	absexp8(An,Rn)


	memory direct, short		absexp16.S

	memory direct, long		absexp32


	PC relative				relexp(PC)

						relexp


	PC relative, indexed		relexp(PC,Rn)

						relexp(Dn)


	immediate				#absexp


	relative branches			relexp



Notes on the addressing modes:


	1.) Rn may be either Dn or An. A size of .W or .L may 
be specified - the default is .W.


	2.) absexp stands for absolute expression. relexp 
stands for relative expression. Relative expressions are 
expressions whose values are defined relative to the current 
PC. Unless specifically defined as absolute, all symbols are 
interpreted as relative expressions by McAsm.


	3.) SP may be used in place of A7 anywhere A7 is 
allowed.


	4.) The numbers after absexp represent the 
maximum size of the expression which is allowed (in bits).


	5.) An immediate operand must be an absolute 
expression.


	6.) McAsm will automatically make the following 
transpositions on address modes:


		0(An)		->	(An)

		(An,Rn)	->	0(An,Rn)

		relexp(Dn)	->	relexp(PC,Dn)

		relexp	->	relexp(PC)


	6.) As noted above, if a relative symbol is used as an 
operand, McAsm will default the addressing mode to PC relative 
- the (PC) suffix is not required.



OPCODE CONVERSIONS


	In certain cases, McAsm will generate object code 
for an opcode different than the opcode specified in the source 
line. There are two situations that will cause this conversion:


	* an address register direct or immediate 
addressing mode has been specified which is not legal for the 
specified opcode but which is legal for a variant of the opcode.


	* a shorter form of the instruction results by using 
the 'Quick' form of the opcode.


	The following opcode conversions will be made 
automatically under the following conditions:


	original	converted	conditions

	ADD		ADDA		if destination is An

	ADD		ADDI		if source is immediate and

						destination is not Dn

	ADD		ADDQ		if immediate is 1-8

	CMP		CMPA		if destination is An

	CMP		CMPI		if source is immediate and

						destination is not Dn

	MOVE		MOVEA	if destination is An

	MOVE		MOVEQ	if immediate is 0-255

	SUB		SUBA		if destination is An

	SUB		SUBI		if source is immediate and

						destination is not Dn

	SUB		SUBQ		if immediate is 1-8



OPCODE SIZES


	McAsm allows size suffixes on those opcodes that 
have more than one size of operation. The allowable opcode size 
suffixes and their uses are as folows:


	.B	operand size is byte

	.W	operand size is word

	.L	operand size is long

	.S	memory direct address is short (one word),

		or relative branch is short (-128...+127)


ARITHMETIC EXPRESSIONS


	The following operators and special characters are 
supported. (All arithmetic and logical operations are 32-bit 
operations.) 


	+	integer addition

	-	integer subtraction

	/	integer division (32 bits/32 bits = 32 bits)

	*	integer multiplication (32bits * 32 bits = 64 
bits)

	MOD	integer modulus

	SHL	logical shift left (16 SHL 2 = 64)

	SHR	logical shift right (16 SHR 3 = 2)

	AND	logical bit AND

	OR	logical bit OR

	XOR	logical bit eXclusive-OR

	NOT	logical bit inverse


		(the following relational operators return 
true or false;

		 true = $FFFFFFFF and false = 0)

	<=	less than or equal

	<>	not equal

	>=	greater than or equal

	<	less than

	>	greater than

	=	equal to


	'xxxx'	character constant (1-4 characters, right 
justified)

	*	current value of program counter

	$	specifies a hexadecimal number

	%	specifies a binary number


	The expression processor uses standard algebraic 
precedence rules. Precedence may be forced by using 
parentheses.



SYMBOL AND EXPRESSION TYPES


	McAsm considers all expressions and symbols to be 
one of three types of expressions: absolute, relative, and 
external.


	An absolute symbol has a value which does not 
change regardless of where the program is located in memory. A 
reference to an absolute symbol employs the actual value or 
address of the symbol.


	A relative symbol has a value which depends on the 
distance from the program counter to the actual address of the 
symbol. A reference to a relative symbol is accomplished by 
employing an offset in instructions from the current program 
counter to the actual address of the symbol. The offset is the 
difference between where the symbol is actually located in 
memory and the program counter. The offset is unchanging for 
any particular link of a program, so the offset itself is 
absolute.


	External symbols are symbols which are defined in 
other modules and whose values are not known to the 
assembler. McAsm considers all external symbols to be relative 
- you can't REF and DEF absolute symbols.


	Because of the object code format of the .REL files 
produced by McAsm, the ways in which symbols can be combined 
in expressions are limited. The following chart summarizes the 
valid expression combinations.


	Across the top of the chart are the expression 
combinations, where:


	A = absolute

	R = relative

	E = external

	: = any operator


Down the left-hand side of the chart are all of the possible 
expression operators. The intersection of an operator with a 
type combination will give the type of the resulting expression 
(A, R, E, or - if the combination is illegal).



Operator	A:A   A:R   A:E   R:A   R:R   R:E   E:A   E:R   
E:E


  SHL	 A     -     -     -     -     -     -     -     
-

  SHR      A     -     -     -     -     -     -     -     
-

  <=       A     -     -     -     A     -     -     -     
-

  <>       A     -     -     -     A     -     -     -     
-

  >=       A     -     -     -     A     -     -     -     
-

  <        A     -     -     -     A     -     -     -     
-

  >        A     -     -     -     A     -     -     -     
-

  =        A     -     -     -     A     -     -     -     
-

  AND      A     -     -     -     -     -     -     -     
-

  OR       A     -     -     -     -     -     -     -     
-

  XOR      A     -     -     -     -     -     -     -     
-

  +        A     R     -     R     -     -     -     -     
-

  -        A     R     -     R     A     A     -     A     
A

  *        A     -     -     -     -     -     -     -     
-

  /        A     -     -     -     -     -     -     -     
-

  MOD      A     -     -     -     -     -     -     -     
-



Unary	A    R    E

  +       A    R    E

  -       A    -    -

  NOT     A    -    -


HOW McASM TYPES FORWARD REFERENCES


	When McAsm encounters a symbol as an operand and 
that symbol hasn't been defined yet, then McAsm has to guess 
what the type of the symbol will be. The reason it has to decide 
the type is that the type will affect the size of the instruction 
being assembled - a reference to an absolute symbol will 
require a 32-bit address while a reference to a relative symbol 
only requires a 16-bit offset. By convention, McAsm assumes 
that symbols that haven't been defined yet are relative symbols.


	This means that you have to define absolute symbols 
before you use them. If you don't, then the instruction will be 
sized differently on the two assembly passes and you'll get 
PHASE ERRORS galore in your assembly. (A phase error is 
when the address of a symbol changes between pass one and 
pass two.) You get the phase errors because instructions that 
required two bytes of address in pass one will require four 
bytes of address in pass two, because in pass two the symbol 
will now be known to be absolute since McAsm has processed 
all of the file.


RELATIVE BRANCHES


	If you don't specify the .S form of a relative branch, 
then McAsm will use the short form of the opcode 
automatically if both of the following conditions are met: 1.) 
the target address expression doesn't contain any forward 
references, and 2.) the offset to the target address will fit in a 
byte.


	If you do specify the .S form of the opcode and the 
resulting offset won't fit in a byte, then you'll get an error 
message. (You also can't branch short to an external symbol.)


ALIGNMENT


	McAsm will automatically align those things that 
are required to be on an even address (opcodes, constant words 
and longs, trap words, etc.) by stuffing a zero byte in front of 
them if necessary. However, any label on a line that has been 
aligned will still carry the value of the address before the 
alignment - which may be odd! If this happens, McAsm will 
warn you by giving you a LABEL ON ODD ADDRESS warning. If 
that's what you really wanted, then you can ignore the warning, 
otherwise you'll have to change the code accordingly (probably 
by adding an explicit ALIGN pseudo-op) and reassemble.



